This document describes the version 1.0d6 of MacSOUP.
Some important notes first: 1.0d6 is a development version; it is not even a beta or an alpha version. This means that it is not quite complete, some features are not yet implemented (the menu commands for Kill Files are already there, but the functionality is not), the user interface might not stay the way it is now, and it most certainly contains bugs. And this documention is a bit terse at times.
The error handling needs to be improved; especially when there are disk full errors, you are likely to end up with a corrupted database. For now, always make sure that there is enough free disk space available. Same for memory: if you are subscribed to a lot of groups, or have very long epiry settings, you may need to increase MacSOUP’s memory partition (via the Finder’s Get Info command). The behaviour in low-memory situations has been improved quite a bit in this version, but it’s still nowhere near perfect.
The code still contains assert()s, which cause you to drop into the Debugger when certain internal errors occur (happens very rarely to me, though). For this reason it is desirable that you have MacsBug installed, if possible (latest version is 6.5d9, available from ftp.info.apple.com). Otherwise, you will get an “Unimplemented Trap” alert in such a situation. Should hopefully never happen, though.
MacSOUP doesn't implement the full SOUP specification yet (in fact, it doesn't even meet all the “minimal conformance” requirements). It only recognizes the encoding types that uqwk produces, namely "un" for news and "bn" for mail. If you use uqwk to produce SOUP packets (like most people will do), this will be no problem; however, if you get your SOUP packets from somewhere else (like for example Solar on a Waffle BBS), you might get an “encoding type not supported” error while importing a packet. In this case, just drop me a line and I'll add support for it.
• What is MacSOUP?
It's free. :-)
MacSOUP is an offline news and mail reader for the Macintosh. Offline means that you connect to your Unix host, collect all your unread mail and news into a single packet, download this packet, and log off; you can then read this packet offline, write replies, post articles etc while you are disconnected, and then you log back on and upload your replies, again as a single packet.
To use MacSOUP, you need a Unix shell account. It doesn't work with a SLIP account or a direct TCP connection (unless you also have a Unix shell somewhere to which you can telnet). I’m planning to add direct MacTCP support to MacSOUP some time, though.
• System requirements
MacSOUP requires System 7.0 or later. It should run on all Macs from the Plus on (let me know if it doesn't run on yours!).
• How do I install MacSOUP?
Put it anywhere on your hard disk. That's all.
MacSOUP has an internal database where it keeps all the articles and messages, and other stuff. Initially, this database is created in your system folder; you can use the Preferences dialog to move it elsewhere, if you want. Do not mess with the files in the MacSOUP Database folder.
MacSOUP has to know which time zone you are in, so that it can build correct “Date:” headers; for this reason you have to set your location in the Map control panel (that's “Weltkarte”, for us Germans). MacSOUP will warn you if you haven't done this yet.
It is also a good idea to install something that takes care of daylight savings time for you; I recommend AutoClock for this purpose (but please only use version 1.4.3 or newer - latest version is 1.4.4). This also sets your Map location, so that you don't even have to do it yourself. Instead of AutoClock, you can also use the Daylight! control panel.
If you don't install such a utility, you have to manually adjust the time zone field of the Map control panel twice a year. When daylight savings time begins, add one hour to the time zone value; when it ends, subtract one hour.
• How do I produce a SOUP packet?
On your unix host, you need a programm called uqwk. You can get this from ftp.gte.com in the directory /pub/uqwk/. Be sure to only use the latest version, which is 1.8 (as of September 1994). If it isn't already installed at your site, you have to compile it first; refer to the uqwk documentation for details, or ask your system administrator.
To build a SOUP packet, you call uqwk like this:
uqwk +m +n +L -B0
(the last letter is a zero, not the letter O). This produces a couple of files, namely an AREAS file which serves as an index for the packet, and a bunch of *.MSG files each of which contains the messages from one newsgroup. You can now combine these files into one SOUP packet with this command:
zip -m soup.zip AREAS *.MSG
Instead of soup.zip you can choose whatever name you like, but it should end with “.zip”. Finally, you download the packet with the command
sz -ub soup.zip
Be sure to set your terminal program to binary mode, unless it has an automatic binary detection feature.
For more information on these commands and their options, please consult their respective man pages.
You will probably want to create a small shell script that contains all these commands. It might look similar to this:
#!/bin/sh
if [ -f soup.zip ]; then
echo there is already a soup packet!
exit 1
fi
uqwk +m +n +L -B0
zip -m soup.zip AREAS *.MSG
sz -ub soup.zip
• What newsgroups and what articles will be in the packet?
uqwk uses your normal .newsrc file to determine which newsgroups you are subscribed to, and which articles you have already read. To subscribe or unsubscribe, use your online newsreader, or edit the .newsrc directly.
• Importing a SOUP packet
There are several ways to import a packet. The easiest way is to let MacSOUP do it automatically: every time you start MacSOUP, it looks at the location that you have specified in the Preferences dialog under “Packet Locations”. If it finds a packet there, it imports it automatically.
You can also import packets manually by choosing “Import SOUP Packet” from the File menu. And finally, you can simply drag packets onto MacSOUP to have them imported (no matter if MacSOUP is already running or not).
In the previous two paragraphs, “packet” always means either a .zip file or an AREAS file. Normally, you'll import .zip files; MacSOUP unzips the .zip file and deletes it if the unzipping was completed successfully. It then unbatches the packet, and if this was successful too, the AREAS and *.MSG files are deleted as well. However, if there was a problem while unbatching, like e.g. one of the files is corrupt, or the AREAS file contained a group for which no accompanying .MSG file was found, the offending files are not deleted. You can then look if you can fix the problem, and drag the AREAS file onto MacSOUP to try to unbatch it again.
• The Newsgroups window
This window is always visible (you can't close it). It contains a list of your newsgroups and mailboxes. Newsgroups are automatically added to the list as soon as a packet arrives that contains them; so all you have to do to add a group is subscribe to it on the unix host. You can delete a newsgroup if you want, but you should remember to also unsubscribe from it on the unix side, otherwise it is likely to be recreated with the arrival of the next packet.
Mailboxes are not created automatically. Initially, there's only one mailbox, called “Main Mailbox”; this is where all mail arrives that you haven't specifically routed elsewhere. You can create additional mailboxes; for each of these you can specify a list of addresses that are automatically routed to this mailbox. [Note: I'm not sure how well this works with mailing lists. Suggestions welcome. And, in a future version of MacSOUP you will hopefully be able to filter mail not only by addresses, but also by keywords found in the Subject: line.]
You can reorder the list of newsgroups simply by dragging groups up or down. While you drag, a black line appears that shows where the group would end up if you let go the mouse button now. The same works for the mailbox list, of course.
Some keyboard shortcuts in the Newsgroups window:
◊ up-arrow/down-arrow: should be pretty obvious…
◊ command-up-arrow: move to the top of the window; if we're
already there, scroll up one page
◊ likewise for command-down-arrow
◊ option-up/down-arrow: move to the very top/bottom of the list
◊ return or enter: open the hilighted group or mailbox
◊ space: open the next group or mailbox that has unread messages
◊ 'i': same as command-i (see next section).
• Newsgroup Settings
You can use this dialog to specify how many articles you want to keep in a newsgroup. All newsgroups are expired every time a new packet is imported. For each group you can choose to either keep the articles of the last so many days (articles older than that are deleted), or keep at most so many articles (if there are more articles than that, the oldest ones are deleted).
In the Preferences dialog you can specify a set of defaults that initially apply to newly created groups. Note that these settings have no effect on existing groups.
Mailboxes are not expired automatically.
• Mailbox Settings
In this dialog you can change a mailbox's name, and you can enter addresses that are automatically routed to this mailbox (except for the Main Mailbox). You may enter the addresses in one of these formats:
stk@contrib.de
stk@contrib.de (Stefan Kurth)
Stefan Kurth <stk@contrib.de>
• The Subject window
This window is opened when you open a newsgroup or mailbox from the Newsgroups window. If another group was already open, it is closed first; you can only have one group or mailbox open at a time.
The window presents a list of articles or mail messages. On the left side, you see the authors (only the real names, if available), in the middle a number that indicates the number of lines in the message, and on the right side the subject. To save space, a “Re:” in front of the subject line is displayed as “>” instead. (Btw, the default font for the subject window is Geneva 12, but actually I prefer Geneva 10. I didn't make this the default, because Geneva 10 isn't available on every Mac; it only looks good if 10pt is installed as a bitmap font.)
At the top left corner of the window there's a popup menu that lets you coose which messages are displayed in the window. You can choose among “Read”, “Unread”, or “All”, or you can choose “Selected” (more about selecting messages in a moment), or finally “New”, which shows you only those messages that arrived with the last packet (if the last packet didn't have any messages for this group, it shows those messages that arrived with the last packet that did have messages for this group).
Messages that you have already read (or marked as read) are displayed in italics.
In the top right corner you see two numbers: the first one shows how many messages are currently selected, and the second shows how many messages are currently displayed in the window.
For mailboxes, you get an additional popup menu where you can specify in what order you want to have the messages displayed. For newsgroups, articles are always sorted by thread order, and the threads are sorted alphabetically.
You can select articles for reading by clicking to the left of the author name, or pressing return when the article is highlighted. This will normally select the entire thread. Selected messages are marked with a black circle on the left of the author name. If you want to select only a single article rather than the whole thread, hold down any of the modifier keys (shift, command, or option). You can uncheck the Preferences option “Select entire threads by default” to reverse this behaviour.
When you have selected as many articles as you want to read at once, you can press space to read them (this will open the message window, which is described in greater detail below). After reading the last selected article, you are automatically returned to the subject window, where you can select more articles if you want, or mark all remaining articles as read (by pressing command-E).
Pressing <Enter> opens the currently highlighted message, regardless of whether it is selected for reading or not.
As soon as you open a message, it is marked as read, which means that if you have the “Show” popup menu set to “Unread”, it will instantly disappear from the list. Btw, crossposted articles are marked as read in all groups that they are posted to, so that you only see them once.
Here's a summary of the keyboard shortcuts:
◊ arrow keys work just like in the Newsgroups window
◊ return: select or deselect threads (or single messages)
◊ enter: open highlighted message
◊ space: open first selected message (if you press space but the subject
window is empty, you are returned to the Newsgroups window)
◊ '1' though '5': same as command-1 through command-5 (change the
“Show” popup menu setting)
◊ any other letter key: scroll to the first subject that begins
with this letter
• The Message window
There is only one message window, which means that you can have only one message open at a time.
For news articles, the message window is divided into two parts: a graphical thread display at the top, and the message text below that (mail messages don't have a thread display, of course). Each of the two parts can be scrolled seperately. The thread display is always automatically scrolled so that the current article is as close to the middle of the display area as possible.
In the thread display, unread articles are displayed as circles with a small cross in the middle; the current article is displayed as a circle filled with a black dot; read articles are displayed as empty circles; and unavailable articles (articles that have already expired, or that didn't arrive yet) are displayed as grey circles.
You can click in the graphical thread display to switch to other articles in the thread. You can also type left-arrow to switch to the current article's “parent”, if there is one, and right-arrow to switch to its first follow-up.
You can make the thread display area larger or smaller by dragging the small box between the three scroll bars up or down. Note that this sets the _maximum_ size that you ever want to be used for the thread display; if the thread fits into a smaller area, MacSOUP will use as little space as it needs, to give as much room as possible to the message text.
In the lower half of the window, MacSOUP displays both the message header and the message body. You can choose to either have the full header displayed, or a terse header that displays only the important information (normally, you are not likely to be interested in a Path: or References: header, are you?). You can switch between these two possibilities by choosing “Full Headers” or “Terse Headers” from the Options menu, or by pressing command-H; if the message window is frontmost, you can even simply press 'h'.
A terse header for a news article contains (always in this order):
◊ the Newsgroups line (only if the article
is crossposted to more than one group)
◊ the Followup-To line (only if present, and
different from the Newsgroups line)
◊ the Subject line
◊ the From line
◊ the Reply-To line (only if present, and
different from the From line)
◊ an Age line (see below for details)
◊ Organization, if present
◊ X-Newsreader or X-Mailer, if present
An “Age:” pseudo header line is displayed instead of the “Date:” header; it shows you how long ago the article was posted. I find this more useful than having to look at weird time zones; if you don't like it, you can turn it off by unchecking the “Show age instead of date” option in the Preferences dialog. Note: in order to display the Age pseudo header, MacSOUP has to convert the date to local time, and it can only do so if you have set your correct location in the Map control panel. If you haven't done this yet, MacSOUP always displays the Date header instead.
For mail messages, a terse header contains:
◊ the From line
◊ the Reply-To line (only if present, and
different from the From line)
◊ the Subject line
◊ the Cc line, if present
◊ the Age line
◊ Organization, if present
◊ X-Newsreader or X-Mailer, if present
Note: your mailboxes contain not only the messages that you receive, but also the messages that you write yourself (MacSOUP automatically saves a copy of all your outgoing mail to the respective mailboxes). Of course, when you read your own messages, the To line is displayed instead of the From and Reply-To lines.
[ Should it be configurable exactly what gets displayed in a terse header (à la trn)? Sometimes I think so, maybe I'll add it some day. ]
Keyboard shortcuts in the message window:
◊ up/down-arrow: scroll by one line
◊ command-up/down-arrow: scroll by one page
◊ option-up/down-arrow: scroll to the very top/bottom
◊ left arrow: go to this article's “parent”, if it has one
(for mail messages: go to the message that comes before
this one in the subject window)
◊ right arrow: go to this article's first follow-up, if it has one
(for mail messages: go to the message that comes after
this one in the subject window)
◊ enter or 'n': go to the next selected message; if there are no
more selected messages, close the message window and
return to the subject window
◊ space: scroll down one page; if we are at the bottom of the
message, go to the next selected message
◊ return: scroll down one line; if we are at the bottom of the
message, go to the next selected message
◊ 'b': same as command-'b' (go back to the previously displayed message)
repeatedly pressing 'b' toggles between the two most recently
displayed messages
◊ 'h': same as command-'h' (toggle full/terse headers)
◊ 'f': same as command-'f' (write a follow-up to this article)
◊ 'r': same as command-'r' (write an email reply)
◊ '+': same as command-'+' (auto-select sub-thread - see next section for details)
◊ '-': same as command-'-' (auto-kill sub-thread)
◊ option-'+': same as command-option-'+' (auto-select thread)
◊ option-'-': same as command-option-'-' (auto-kill thread)
• Auto-Selecting and Auto-Killing
You can auto-select or auto-kill entire threads or branches of a thread (sub-threads). If an article is auto-selected, any future follow-ups to this article will automatically be selected for reading when you open the group. This is useful if you read something interesting, and you want to make sure that you don't overlook any further discussion of the topic. (Your own postings are auto-selected automatically for you, to make it unlikely that you'll miss any replies to your posts).
If an article is auto-killed, any future follow-ups to it will automatically be marked as read as soon as they come in, so that you won't see them if the “Show:” popup menu is set to “Unread”. But they are added to the news database, so you can read them if you set the “Show:” popup menu to “Read”, “All”, or “New”.
Auto-selected articles are marked with a little '+' in the thread display (and in the subject window), and auto-killed articles with a '-'.
“Auto-select thread” means that all articles in the entire thread are auto-selected; “auto-select sub-thread” means only the currently displayed article and all its follow-ups are auto-selected.
Auto-selecting and -killing is possible from both the subject window and the message window. However (at least for sub-threads) I recommend to do it only from the message window, because there you see exactly what gets selected or killed.
• The message editor
If you write a follow-up or an email reply, a message editor window is opened. In this window you can fill in some header stuff (you can go from one header field to the next by pressing tab or return), and type the message text itself, of course. The message text is automatically wrapped to 72 columns (except for quoted lines, which are not wrapped. If you try to send the message and it contains quoted lines that are longer than 80 characters, you are warned about this). While you are editing the message, you always see exactly how the message will be wrapped when it goes out. (This is not true when you make the editor window narrower than 72 columns: in this case the text is wrapped to the window width while you are editing it, but it is wrapped to 72 columns when it goes out. Also, quoted lines are always wrapped to the window width while you are editing, but they are not wrapped at all when the message is sent.)
You can re-wrap quoted text with the “Re-Wrap Text” command in the Edit menu. Select the text that you want to have wrapped; MacSOUP will first extend the selection so that it includes only entire lines. It will then divide the selection into paragraphs, and wrap each paragraph seperately. This command does not only break long lines into shorter ones, but it also merges short lines that fit on one line (some text editors call this command “Paragraph Fill”). For each paragraph MacSOUP looks if there is a quote prefix (a string of characters that is present at the beginning of every line), and preserves it. Paragraphs can only be recognized when they are seperated by blank lines (or by lines that contain nothing but the respective quote prefix). Experiment with this a bit to see how it works.
You can use tabs in the message body (currently hard-coded to 8 spaces; should probably be configurable); when the message is sent, they are converted to spaces. If you want to jump from the message body to the first header field, you must press command-tab.
If you write a reply to a news article, you get an additional popup menu at the top of the editor window that you can use to switch between follow-up and email reply. You can switch at any time, even after you have closed and re-opened the window. This can sometimes be useful if you press 'f', and after spending half an hour on writing a long message you realise that this isn't really of interest to everyone, and you'd rather send it by email instead (or vice versa).
You can have as many editor windows open as you like. You can close them, re-open them to make further changes, or delete them if you change your mind. To delete a message, you have to open it first (from the “Outgoing Mail & News” window, see below), and press the “Delete” button.
If you try to close an editor window, MacSOUP checks if the message is basically ok. For example, it makes sure that you haven't left the Subject line blank, and it checks whether the To line contains something that looks like a valid Internet address, or whether you are attempting to post to a newsgroup that you are not subscribed to, and a couple other things. If there are any problems, MacSOUP won't let you close the window (this also means that you can't quit MacSOUP when there are incorrect editor windows open, because MacSOUP always tries to close all windows before it quits).
You will rarely need to type into the Newsgroups:, Followup-To:, To:, Cc:, and Bcc: fields directly, because there's an extra feature that does this for you. You can click on the field labels (eg. the word “Newsgroups:”) to get a popup menu of either the subscribed groups or the entries in your address book, depending on whether you are composing a news article or a mail message. Whatever you choose from this menu gets appended to the respective text field.
[ A note to the HIG cops: I know that this feature violates the Human Interface Guidelines, because the field labels can't be easily recognized as popup menus unless you accidentally click on them (or point the mouse to them with Balloon Help on), which means that people who don't read manuals will probably never find out about the feature. However, I didn't want to put “real” popup menus in these places, because they would simply take up too much space. ]
Here's a summary of how keys work in the editor:
◊ command-up-arrow: go to the first line that is currently
being displayed in the window; if we're already in the
first line, scroll up one page
◊ likewise for command-down-arrow
◊ command-left/right-arrow: go to the beginning/end of the line
◊ option-up/down-arrow: go to the very top/bottom of the text
◊ option-left/right-arrow: move by one word
◊ holding down shift with any of the above extends the selection
◊ tab: move to the next header field (use command-tab
to step out of the message body)
◊ shift-tab: move to the previous header field
• The “Outgoing Mail & News” window
This window contains a list of all the messages that you have written so far. It looks and behaves similar to the subject window, so there's not much to explain here (except that you can't select messages; pressing return opens the highlighted message instead).
Mail messages are marked with the letter 'M', and news articles with 'N'.
• Reply packets
After you have written some messages, you want to build a reply packet that you can upload to the Unix host. You can do this manually by choosing “Make Reply Packet” from the File menu. However, you'll rarely need this command, because when you quit MacSOUP and there are unsent messages, it asks you whether you want to have a reply packet built before quitting. If you answer No to this question, your messages are left there, and you can edit them again next time you run MacSOUP. If you answer Yes, a reply packet is built (under the name and location that you have specified in the Preferences dialog; default is on your desktop under the name “reply.zip”), and the messages are removed from the “Outgoing Mail & News” window.
You can now upload the packet to the Unix host. You then need to unzip it there, using the command
unzip reply.zip
(or whatever name you have chosen), and then feed it to uqwk like this:
uqwk -m -n +L -RREPLIES
You will probably want to remove it afterwards, with the command
rm reply.zip
Again, you probably want to make yourself a small shell script to automate this process. Something like this might do:
#!/bin/sh
if [ ! -f reply.zip ]; then
echo no reply packet found
exit 1
fi
unzip reply.zip
uqwk -m -n +L -RREPLIES
rm reply.zip
• A note about character sets
MacSOUP has no MIME support yet. It simply treats every incoming message as ISO-latin-1, regardless of its MIME headers. For things that you write, MacSOUP checks if the message contains any 8-bit characters (these are certain national characters like German umlauts or French accented letters etc.); if it does, it translates them to ISO-latin-1 and includes the proper MIME headers; if not, no MIME headers are included. You can specify whether you want to be warned when you have inadvertently used 8-bit characters (in the Newsgroups Settings dialog, seperately for each newsgroup).
In Usenet news it is generally acceptable to use 8-bit characters, but most mail connections are limited to 7 bit.
• Phew!
Are you still reading? I hope I didn't forget anything. If anything is still unclear to you, just tell me (I'm well aware that I'm not a good manual writer).
If you find any bugs, please report them with as many details as you can provide. If you ever happen to be dropped into MacsBug with an “internal error” message, simply type “g <return>”; this will take you back to the Finder and create a file called error_log somewhere on your hard disk which might help me track down the bug.
If you have any suggestions, I'm all ears. However, instead of mailing them to me, I'd suggest that you post them to either comp.sys.mac.comm or alt.usenet.offline-reader, so that they can be discussed by everyone. I'll try to read these two groups as regularly as I can.
